Adding Joins to a Shape (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Adding Joins to a Shape
To add a join shape to the corners of another shape's contours, you must create a join structure. The join structure has three fields: one for the join shape, one for the join attributes, and one for the miter, which is used only for sharp joins.
Listing 3-11 shows how to create a join structure with an diamond shape as the join shape, and then apply the diamond join shape to the corners of a rectangle shape.
Listing 3-11 Adding joins to a shape
void CreateJoinedSquare(void)
{
   gxShape  aSquareShape, aDiamondShape;

   static gxRectangle squareGeometry = {ff(50), ff(50), 
                                        ff(150), ff(150)};
      
   static long diamondGeometry[] = {1, /* number of contours */
                                    4, /* number of points */
                                    ff(0), ff(3), 
                                    ff(1), fl(0),
                                    ff(0), -ff(3), 
                                    -ff(1), ff(0)};
      
   gxJoinRecord theJoinRecord;
   
   
   aSquareShape = GXNewRectangle(&squareGeometry);
   GXSetShapeFill(aSquareShape, gxClosedFrameFill);

   aDiamondShape = GXNewPolygons((gxPolygons *) diamondGeometry);
      
   theJoinRecord.attributes = gxNoAttributes;
   theJoinRecord.join = aDiamondShape;
   theJoinRecord.miter = 0; 

   GXSetShapeJoin(aSquareShape, &theJoinRecord);
   
   GXDisposeShape(aDiamondShape);
      
   GXSetShapePen(aSquareShape, ff(10));
   
   GXDrawShape(aSquareShape);
   
   GXDisposeShape(aSquareShape);
}
This sample function creates a square as the shape to add joins to and a diamond-shaped polygon to use for the joins. It then creates a join structure which contains a reference to the diamond shape, an attributes field with no attributes set, and a miter of 0.
The sample function then calls the GXSetShapeJoin function, which sets the join property of the square shape's style object. (Remember, it makes a copy of this style object if the style is shared amongst multiple shapes.)

Note
As with caps, QuickDraw GX copies only the geometric information of the join shape into the join property of the style object; it does not copy the entire join shape. For this reason, join shapes must be in their primitive form. Once you have called GXSetShapeJoin, you are free to change the original join shape without affecting the joins that you have already added to a shape.
After the CreateJoinedSquare sample function sets the joins of the square shape, it disposes of the diamond-shaped polygon. At this point, the owner count of this polygon shape becomes 0 and the memory used by the polygon shape is freed.
Figure 3-55 shows the result of the CreateJoinedSquare sample function.
Figure 3-55 A square with diamond-shaped joins

Notice that QuickDraw GX scales the join shape by the pen width and rotates the join shape to match the mid-angle of the two line segments that make each corner. You can suppress the rotation by setting the level join attribute:
theJoinRecord.attributes = gxLevelJoin;
Figure 3-56 shows the result of setting this attribute.
Figure 3-56 A square with level joins

The sections "The Join Structure" on page 3-101 and "Join Attributes" on page 3-102 describe the join structure and join attributes in more detail, and the section "Getting and Setting Joins" beginning on page 3-129 describes the functions you can use to manipulate joins.
The next section shows how to create standard joins and how to use the miter field of the join structure.